From: Carlos Garnacho Date: Fri, 1 Dec 2017 23:18:07 +0000 (+0100) Subject: gtkeventcontrollerscroll: Add some docs X-Git-Tag: archive/raspbian/3.24.39-1+rpi1~1^2~65^2~34^2~4^2~11 X-Git-Url: https://dgit.raspbian.org/%22http://www.example.com/cgi/success/%22http:/www.example.com/cgi/success?a=commitdiff_plain;h=448551f31c0d7323b593d9ac7e293a1df8ba57aa;p=gtk%2B3.0.git gtkeventcontrollerscroll: Add some docs --- diff --git a/docs/reference/gtk/gtk3.types.in b/docs/reference/gtk/gtk3.types.in index 9f7d51234e..45b28bc20a 100644 --- a/docs/reference/gtk/gtk3.types.in +++ b/docs/reference/gtk/gtk3.types.in @@ -65,6 +65,7 @@ gtk_entry_completion_get_type gtk_entry_get_type gtk_event_box_get_type gtk_event_controller_get_type +gtk_event_controller_scroll_get_type gtk_expander_get_type gtk_file_chooser_button_get_type gtk_file_chooser_dialog_get_type diff --git a/gtk/gtkeventcontrollerscroll.c b/gtk/gtkeventcontrollerscroll.c index 57991db1ae..f0816a5d65 100644 --- a/gtk/gtkeventcontrollerscroll.c +++ b/gtk/gtkeventcontrollerscroll.c @@ -17,6 +17,47 @@ * Author(s): Carlos Garnacho */ +/** + * SECTION:gtkeventcontrollerscroll + * @Short_description: Event controller for scroll events + * @Title: GtkEventControllerScroll + * @See_also: #GtkEventController + * + * #GtkEventControllerScroll is an event controller meant to handle + * scroll events from mice and touchpads. It is capable of handling + * both discrete and continuous scroll events, abstracting them both + * on the #GtkEventControllerScroll::scroll signal (deltas in the + * discrete case are multiples of 1). + * + * In the case of continuous scroll events, #GtkEventControllerScroll + * encloses all #GtkEventControllerScroll::scroll events between two + * #GtkEventControllerScroll::scroll-begin and #GtkEventControllerScroll::scroll-end + * signals. + * + * The behavior of the event controller can be modified by the + * flags given at creation time, or modified at a later point through + * gtk_event_controller_scroll_set_flags() (e.g. because the scrolling + * conditions of the widget changed). + * + * The controller can be set up to emit motion for either/both vertical + * and horizontal scroll events through #GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, + * #GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and #GTK_EVENT_CONTROLLER_SCROLL_BOTH. + * If any axis is disabled, the respective #GtkEventControllerScroll::scroll + * delta will be 0. Vertical scroll events will be translated to horizontal + * motion for the devices incapable of horizontal scrolling. + * + * The event controller can also be forced to emit discrete events on all devices + * through #GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement + * discrete actions triggered through scroll events (e.g. switching across + * combobox options). + * + * The #GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the + * #GtkEventControllerScroll::decelerate signal, emitted at the end of scrolling + * with two X/Y velocity arguments that are consistent with the motion that + * was received. + * + * This object was added in 3.93. + **/ #include "config.h" #include "gtkintl.h" @@ -318,6 +359,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) controller_class->handle_event = gtk_event_controller_scroll_handle_event; + /** + * GtkEventControllerScroll:flags: + * + * The flags affecting event controller behavior + * + * Since: 3.93 + **/ pspecs[PROP_FLAGS] = g_param_spec_flags ("flags", P_("Flags"), @@ -327,6 +375,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY); + /** + * GtkEventControllerScroll::scroll-begin: + * @controller: The object that received the signal + * + * Signals that a new scrolling operation has begun. It will + * only be emitted on devices capable of it. + **/ signals[SCROLL_BEGIN] = g_signal_new (I_("scroll-begin"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -334,6 +389,15 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) 0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + /** + * GtkEventControllerScroll::scroll: + * @controller: The object that received the signal + * @dx: X delta + * @dy: Y delta + * + * Signals that the widget should scroll by the + * amount specified by @dx and @dy. + **/ signals[SCROLL] = g_signal_new (I_("scroll"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -341,6 +405,13 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) 0, NULL, NULL, _gtk_marshal_VOID__DOUBLE_DOUBLE, G_TYPE_NONE, 2, G_TYPE_DOUBLE, G_TYPE_DOUBLE); + /** + * GtkEventControllerScroll::scroll-end: + * @controller: The object that received the signal + * + * Signals that a new scrolling operation has finished. It will + * only be emitted on devices capable of it. + **/ signals[SCROLL_END] = g_signal_new (I_("scroll-end"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -348,6 +419,18 @@ gtk_event_controller_scroll_class_init (GtkEventControllerScrollClass *klass) 0, NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * GtkEventControllerScroll::decelerate: + * @controller: The object that received the signal + * @vel_x: X velocity + * @vel_y: Y velocity + * + * Emitted after scroll is finished if the #GTK_EVENT_CONTROLLER_SCROLL_KINETIC + * flag is set. @vel_x and @vel_y express the initial velocity that was + * imprinted by the scroll events. @vel_x and @vel_y are expressed in + * pixels/ms. + **/ signals[DECELERATE] = g_signal_new (I_("decelerate"), GTK_TYPE_EVENT_CONTROLLER_SCROLL, @@ -366,6 +449,18 @@ gtk_event_controller_scroll_init (GtkEventControllerScroll *scroll) sizeof (ScrollHistoryElem)); } +/** + * gtk_event_controller_scroll_new: + * @widget: a #GtkWidget + * @flags: behavior flags + * + * Creates a new event controller that will handle scroll events + * for the given @widget. + * + * Returns: a new #GtkEventControllerScroll + * + * Since: 3.93 + **/ GtkEventController * gtk_event_controller_scroll_new (GtkWidget *widget, GtkEventControllerScrollFlags flags) @@ -378,6 +473,15 @@ gtk_event_controller_scroll_new (GtkWidget *widget, NULL); } +/** + * gtk_event_controller_scroll_set_flags: + * @scroll: a #GtkEventControllerScroll + * @flags: behavior flags + * + * Sets the flags conditioning scroll controller behavior. + * + * Since: 3.93 + **/ void gtk_event_controller_scroll_set_flags (GtkEventControllerScroll *scroll, GtkEventControllerScrollFlags flags) @@ -391,6 +495,16 @@ gtk_event_controller_scroll_set_flags (GtkEventControllerScroll *scroll, } } +/** + * gtk_event_controller_scroll_get_flags: + * @scroll: a #GtkEventControllerScroll + * + * Gets the flags conditioning the scroll controller behavior. + * + * Returns: the controller flags. + * + * Since: 3.93 + **/ GtkEventControllerScrollFlags gtk_event_controller_scroll_get_flags (GtkEventControllerScroll *scroll) { diff --git a/gtk/gtkeventcontrollerscroll.h b/gtk/gtkeventcontrollerscroll.h index a7303f88d8..d1d33366c7 100644 --- a/gtk/gtkeventcontrollerscroll.h +++ b/gtk/gtkeventcontrollerscroll.h @@ -39,6 +39,20 @@ G_BEGIN_DECLS typedef struct _GtkEventControllerScroll GtkEventControllerScroll; typedef struct _GtkEventControllerScrollClass GtkEventControllerScrollClass; +/** + * GtkEventControllerScrollFlags: + * @GTK_EVENT_CONTROLLER_SCROLL_NONE: Don't emit scroll. + * @GTK_EVENT_CONTROLLER_SCROLL_VERTICAL: Emit scroll with vertical deltas. + * @GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL: Emit scroll with horizontal deltas. + * @GTK_EVENT_CONTROLLER_SCROLL_DISCRETE: Only emit deltas that are multiples of 1. + * @GTK_EVENT_CONTROLLER_SCROLL_KINETIC: Emit #GtkEventControllerScroll::decelerate + * after continuous scroll finishes. + * @GTK_EVENT_CONTROLLER_SCROLL_BOTH_AXES: Emit scroll on both axes. + * + * Describes the behavior of a #GtkEventControllerScroll. + * + * Since: 3.93 + **/ typedef enum { GTK_EVENT_CONTROLLER_SCROLL_NONE = 0, GTK_EVENT_CONTROLLER_SCROLL_VERTICAL = 1 << 0,